AI Service > OCR > Document OCR > API v2.0 Guide

Overview of v2.0 API

Changes from v1.0

• Enhanced security with the electronic envelope method.

Domain

Name	Domain
OCR Public API Domain	https://ocr.api.nhncloudservice.com

Prerequisites (AppKey, SecretKey)

• AppKey and SecretKey are required to use the API.
• You can find the {appKey} and {secretKey} in the URL & Appkey menu at the top of the console.

Caution

• Check whether the request or response is Base64 encoded.
• Check the detailed mode of encryption and decryption (eg AES-256/CBC/PKCS7Padding).
• The symmetric key used for encryption must be generated as a 32 byte random number. For security, it is recommended to create and use a new symmetric key for each request.

Issue Public Key

Request

• You can find the {appKey} and {secretKey} in the URL & Appkey menu at the top of the console.

[URI]

Method	URI
GET	/v2.0/appkeys/{appKey}/public-keys/{serviceName}

[Request Header]

Name	Value	Description
Authorization	{secretKey}	Security key issued from the console

[Path Variable]

Name	Value	Description
appKey	{appKey}	Integrated Appkey or Service Appkey
serviceName	{serviceName}	credit-card (when issuing the public key used for calling the credit card API), id-card (when issuing the public key used for calling the ID card API)

[Request Body]

curl -X GET 'https://ocr.api.nhncloudservice.com/v2.0/appkeys/{appKey}/public-keys/{serviceName}' \
-H 'Authorization: ${secretKey}'

Response

[Response Body]

{
  "header": {
    "isSuccessful": true,
    "resultCode": 0,
    "resultMessage": "SUCCESS"
  },
  "result": {
    "key": "String",
    "version": "0"
  }
}

[Header]

Name	Type	Description
isSuccessful	Boolean	API success or not
resultCode	Integer	Result code
resultMessage	String	Result message (success on success, error content on failure)

[Field]

Name	Type	Description
result	Object	Public key required for encryption
result.key	String	Public key (Base64 encoded)
result.version	String	version of public key

• The public key is Base64 encoded.

Credit Card API

Credit Card Analysis API

Request

• You can find the {appKey} and {secretKey} in the URL & Appkey menu at the top of the console.

[URI]

Method	URI
POST	/v2.0/appkeys/{appKey}/credit-card

[Request Header]

Name	Value	Description
Authorization	{secretKey}	Security key issued from the console
X-Key-Version	{x-key-version}	Version of the public key issued
Symmetric-Key	{symmetricKey}	Symmetric key encrypted with the issued public key

• {symmetricKey} must be created as a 32-byte random number.
• {symmetricKey} must be encrypted with the RSA/ECB/PKCS1Padding method (using public key).

[Path Variable]

Name	Value	Description
appKey	{appKey}	Integrated Appkey or Service Appkey

[Field]

Name	Type	Description	Encryption Description
image	multipart/form-data	Image file	Image encrypted with a symmetric key

• Image files must be encrypted with the AES-256/CBC/PKCS7Padding method (using a symmetric key).

[Request Body]

curl -X POST 'https://ocr.api.nhncloudservice.com/v2.0/appkeys/{appKey}/credit-card' \
-F 'image=@sample.png' \
-H 'Authorization: ${secretKey}' \
-H 'X-Key-Version: ${x-key-version}' \
-H 'Symmetric-Key: ${symmetricKey}'

Response

[Response Body]

{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": "SUCCESS"
    },
    "result": {
        "fileType": "png",
        "resolution": "low",
        "cardNums": [
                    {
                        "value": "1111",
                        "conf": 0.87
                    },
                    {
                        "value": "2222",
                        "conf": 0.99
                    },
                    {
                        "value": "3333",
                        "conf": 0.97
                    },
                    {
                        "value": "4444",
                        "conf": 0.89
                    }
        ],
        "totalCardNum": "111222233334444",
        "cardNumBoxes": [
            {
                "x1": 62,
                "y1": 256,
                "x2": 192,
                "y2": 256,
                "x3": 192,
                "y3": 301,
                "x4": 62,
                "y4": 301
            },
            ...
        ],
        "validThru": {
            "value": "04/19",
            "conf": 0.53
        },
        "validThruBox": {
            "x1": 316,
            "y1": 315,
            "x2": 426,
            "y2": 315,
            "x3": 426,
            "y3": 347,
            "x4": 316,
            "y4": 347
        }
    }
}

[Header]

Name	Type	Description
isSuccessful	Boolean	Analysis API success or not
resultCode	Integer	Result code
resultMessage	String	Result message (success on success, error content on failure)

[Field]

Name	Type	Description	Whether encrypted or not
fileType	String	File extension (.jpg, .png)
resolution	String	normal: the resolution is the recommended resolution (760*480px) or above, low: the resolution is below the recommended resolution
cardNums	List	List of card number recognition results
cardNums[0].value	String	Recognition result	O
cardNums[0].conf	Double	Confidence of the recognition result
totalCardNum	List	Full card number recognition result	O
cardNumBoxes	List	List of coordinates of the card number recognition area (bounding box)
cardNumBoxes[0]	Object	Coordinates of recognized area { x1, y1, x2, y2, x3, y3, x4, y4 }
validThru.value	String	Expiration date recognition content	O
validThru.conf	Double	Confidence of expiration date recognition result
validThruBox	Object	Coordinates of the expiration date recognition area { x1, y1, x2, y2, x3, y3, x4, y4 }

• Encrypted items (cardNums[0].value, totalCardNum, etc.) are encrypted with the AES-256/CBC/PKCS7Padding method (using symmetric key).

• boxes[0]

ID Card Analysis API

Request

• You can find the {appKey} and {secretKey} in the URL & Appkey menu at the top of the console.

[URI]

Method	URI
POST	/v2.0/appkeys/{appKey}/id-card

[Request Header]

Name	Value	Description
Authorization	{secretKey}	Security key issued from the console
X-Key-Version	{x-key-version}	Version of the public key issued
Symmetric-Key	{symmetricKey}	Symmetric key encrypted with the issued public key

• {symmetricKey} must be created as a 32-byte random number.
• {symmetricKey} must be encrypted with the RSA/ECB/PKCS1Padding method (using public key).

[Path Variable]

Name	Value	Description
appKey	{appKey}	Integrated Appkey or Service Appkey

[Field]

Name	Type	Description	Encryption Description
image	multipart/form-data	Image file	Image encrypted with a symmetric key

• Image files must be encrypted with the AES-256/CBC/PKCS7Padding method (using a symmetric key).

[Request Body]

curl -X POST 'https://ocr.api.nhncloudservice.com/v2.0/appkeys/{appKey}/id-card' \
-F 'image=@sample.png' \
-H 'Authorization: ${secretKey}' \
-H 'X-Key-Version: ${x-key-version}' \
-H 'Symmetric-Key: ${symmetricKey}'

Response

[Response Header]

Name	Description
Request-Key	Request-Key to be used when calling the Verify Authenticity API

• If you use the Request-Key to make a Authenticity API call and get a normal response, the Request-Key used cannot be reused.
• Request-Key is valid for 1 hour after issuance and cannot be used after that.

[Response Body]

{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": "SUCCESS"
    },
    "result": {
        "fileType": "png",
        "resolution": "low",
        "idType": "resident",
        "keyValues": [
            {
                "key": "name",
                "value": "String",
                "conf": 0.67,
                "bbox": {
                    "x1": 191,
                    "y1": 75,
                    "x2": 240,
                    "y2": 75,
                    "x3": 240,
                    "y3": 95,
                    "x4": 191,
                    "y4": 95
                }
            },
            {
                "key": "residentNumber",
                "value": "String",
                "conf": 0.91,
                "bbox": {
                    "x1": 190,
                    "y1": 43,
                    "x2": 382,
                    "y2": 43,
                    "x3": 382,
                    "y3": 64,
                    "x4": 190,
                    "y4": 64
                }
            },
            {
                "key": "issueDate",
                "value": "String",
                "conf": 0.86,
                "bbox": {
                    "x1": 191,
                    "y1": 75,
                    "x2": 240,
                    "y2": 75,
                    "x3": 240,
                    "y3": 95,
                    "x4": 191,
                    "y4": 95
                },
            },
            {
                "key": "issuer",
                "value": "String",
                "conf": 0.8,
                "bbox": {
                    "x1": 19,
                    "y1": 10,
                    "x2": 148,
                    "y2": 10,
                    "x3": 148,
                    "y3": 52,
                    "x4": 19,
                    "y4": 52
                }
            }
        ],
        "boxes": [
            {
                "x1": 280,
                "y1": 271,
                "x2": 354,
                "y2": 271,
                "x3": 354,
                "y3": 305,
                "x4": 280,
                "y4": 305
            },
            ...
        ]
    }
}

[Header]

Name	Type	Description
isSuccessful	Boolean	Analysis API success or not
resultCode	Integer	Result code
resultMessage	String	Result message (success on success, error content on failure)

[Field]

Name	Type	Description	Whether encrypted or not
fileType	String	File extension (.jpg, .png)
resolution	String	normal: the resolution is the recommended resolution (760*480px) or above, low: the resolution is below the recommended resolution
idType	String	resident(resident registration certificate), driver(driver license), passport (passport)
keyValues	List
keyValues[0].key	String
keyValues[0].value	String		O
keyValues[0].bbox	Object	Coordinates of recognized area { x1, y1, x2, y2, x3, y3, x4, y4 }
keyValues[0].conf	Double	Confidence of the recognition result
boxes	List	List of bounding box coordinates
boxes[0]	Object	Coordinates of recognized area { x1, y1, x2, y2, x3, y3, x4, y4 }

• List included in KeyValues when "idType" is recognized as "resident"

key	value type	description
name	string	Recognized name
residentNumber	string	Recognized resident registration number
issueDate	string	Recognized issued date
issuer	string	Recognized issuer

• List to be included in KeyValues when "idType" is recognized as "driver"

key	value type	description
driverLicenseNumber	string	Recognized driver license number
licenseType	string	Recognized driver license type (Class 1 Normal, etc.) When the values are 2 or more, separate them with “/”
name	string	Recognized name
residentNumber	string	Recognized resident registration number
condition	string	Recognized driver license condition (If the field does not exist according to the driver's license, the value of the field is none)
serialNum	string	Recognized serial number
issueDate	string	Recognized issued date
issuer	string	Recognized issuer

• List included in KeyValues when "idType" is recognized as "passport"

key	value type	description
passportType	string	Recognized passport type
countryCode	string	Recognized country code
passportNo	string	Recognized passport number
surName	string	Recognized surname
givenName	string	Recognized name
nationality	string	Recognized nationality
dateOfBirth	string	Recognized birthdate
dateOfBirthYMD	string	Recognized birthdate (YYYYMMDD 8 digits)
sex	string	Recognized gender
dateOfIssue	string	Recognized issue date
dateOfIssueYMD	string	Recognized issue date (YYYYMMDD 8 digits)
dateOfExpiry	string	Recognized expiration date
dateOfExpiryYMD	string	Recognized expiration date (YYYYMMDD 8 digits)
koreanName	string	Recognized Korean name
personalNo	string	Recognized resident registration number
MRZ1	string	Machine readable zone 1
MRZ2	string	Machine readable zone 2

• Encrypted items (keyValues[0].value, etc.) are encrypted with the AES-256/CBC/PKCS7Padding method (using symmetric key).
• boxes[0]

Verify Authenticity API

Request

• You can find the {appKey} and {secretKey} in the URL & Appkey menu at the top of the console.

[URI]

Method	URI
POST	/v2.0/appkeys/{appKey}/id-card/authenticity

[Request Header]

Name	Value	Description
Authorization	{secretKey}	Security key issued from the console
X-Key-Version	{x-key-version}	Version of the public key issued
Symmetric-Key	{symmetricKey}	Symmetric key encrypted with the issued public key
Request-Key	{Request-Key}	Request-Key issued after ID card analysis

• {symmetricKey} must be created as a 32-byte random number.
• {symmetricKey} must be encrypted with the RSA/ECB/PKCS1Padding method (using public key).

[Path Variable]

Name	Value	Description
appKey	{appKey}	Integrated Appkey or Service Appkey

[Field]

Name	Type	Description	idType	Whether encrypted or not	Required
idType	String	resident(resident registration certificate), driver(driver license), passport (passport)		X	O
name	String	Name		O	O
residentNumber	String	Resident registration number - For resident (resident registration certificate), 13 digits of resident registration number - For a driver (driver's license), 7 digits that comprise of the first 6 digits and the first 1 digit of resident registration number	resident, driver	O	O
issueDate	String	Issued date (YYYYMMDD)	resident, passport	O	O
driverLicenseNumber	String	12 digits of driver license number	driver	O	O
serialNum	String	5 and 6 digits of serial number	driver	O	X
passportNumber	String	Passport number (9 digits in uppercase letters and numbers)	passport	O	O
birthDate	String	Birthdate (YYYYMMDD)	passport	O	O
expirationDate	String	Expiration date (YYYYMMDD)	passport	X	O

• A field that requires encryption must be encrypted with the AES-256/CBC/PKCS7Padding method (using a symmetric key).

[Request Body]

curl -X POST 'https://ocr.api.nhncloudservice.com/v2.0/appkeys/{appKey}/id-card/authenticity' \
-H 'Authorization: ${secretKey}' \
-H 'X-Key-Version: ${x-key-version}' \
-H 'Symmetric-Key: ${symmetricKey}' \
-H 'Request-Key: ${Request-Key}' \
-H 'Content-Type: application/json' \
--data-raw '{
  "idType": "driver",
  "name": "J/MTycDJ...",
  "residentNumber": "P12ztmj...",
  "driverLicenseNumber": "OHjVJrUMh...",
  "serialNum": "7tnTOKuKGJ..."
}'

Response

[Response Body]

{
  "header": {
    "isSuccessful": true,
    "resultCode": 0,
    "resultMessage": "SUCCESS"
  },
  "result": {
    "isAuthenticity": false
  }
}

[Header]

Name	Type	Description
isSuccessful	Boolean	Whether the Verify Authenticity API succeeds or not
resultCode	Integer	Result code
resultMessage	String	Result message (success on success, error content on failure)

[Field]

Name	Type	Description
isAuthenticity	Boolean	Whether it is authentic or not

ID Card Analysis API (Stand alone)

Differences from the existing ID analysis API

• It does not contain the Request-Key required for authenticity verification.
• Authenticity cannot be verified, but a low fee is charged.

Request

• You can find the {appKey} and {secretKey} in the URL & Appkey menu at the top of the console.

[URI]

Method	URI
POST	/v2.0/appkeys/{appKey}/id-card/stand-alone

[Request Header]

Name	Value	Description
Authorization	{secretKey}	Security key issued from the console
X-Key-Version	{x-key-version}	Version of the public key issued
Symmetric-Key	{symmetricKey}	Symmetric key encrypted with the issued public key

• {symmetricKey} must be created as a 32- byte random number.
• {symmetricKey} must be encrypted with theRSA/ECB/PKCS1Padding method (using public key).

[Path Variable]

Name	Value	Description
appKey	{appKey}	Integrated Appkey or Service Appkey

[Field]

Name	Type	Description	Encryption Description
image	multipart/form-data	Image file	Image encrypted with a symmetric key

• Image files must be encrypted with theAES-256/CBC/PKCS7Padding method (using a symmetric key).

[Request Body]

curl -X POST 'https://ocr.api.nhncloudservice.com/v2.0/appkeys/{appKey}/id-card/stand-alone' \
-F 'image=@sample.png' \
-H 'Authorization: ${secretKey}' \
-H 'X-Key-Version: ${x-key-version}' \
-H 'Symmetric-Key: ${symmetricKey}'

Response

[Response Body]

{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": "SUCCESS"
    },
    "result": {
        "fileType": "png",
        "resolution": "low",
        "idType": "resident",
        "keyValues": [
            {
                "key": "name",
                "value": "String",
                "conf": 0.67,
                "bbox": {
                    "x1": 191,
                    "y1": 75,
                    "x2": 240,
                    "y2": 75,
                    "x3": 240,
                    "y3": 95,
                    "x4": 191,
                    "y4": 95
                }
            },
            {
                "key": "residentNumber",
                "value": "String",
                "conf": 0.91,
                "bbox": {
                    "x1": 190,
                    "y1": 43,
                    "x2": 382,
                    "y2": 43,
                    "x3": 382,
                    "y3": 64,
                    "x4": 190,
                    "y4": 64
                }
            },
            {
                "key": "issueDate",
                "value": "String",
                "conf": 0.86,
                "bbox": {
                    "x1": 191,
                    "y1": 75,
                    "x2": 240,
                    "y2": 75,
                    "x3": 240,
                    "y3": 95,
                    "x4": 191,
                    "y4": 95
                },
            },
            {
                "key": "issuer",
                "value": "String",
                "conf": 0.8,
                "bbox": {
                    "x1": 19,
                    "y1": 10,
                    "x2": 148,
                    "y2": 10,
                    "x3": 148,
                    "y3": 52,
                    "x4": 19,
                    "y4": 52
                }
            }
        ],
        "boxes": [
            {
                "x1": 280,
                "y1": 271,
                "x2": 354,
                "y2": 271,
                "x3": 354,
                "y3": 305,
                "x4": 280,
                "y4": 305
            },
            ...
        ]
    }
}

[Header]

Name	Type	Description
isSuccessful	Boolean	Analysis API success or not
resultCode	Integer	Result code
resultMessage	String	Result message (success on success, error content on failure)

[Field]

Name	Type	Description	Whether encrypted or not
fileType	String	File extension (.jpg, .png)
resolution	String	normal: the resolution is the recommended resolution (760*480px) or above, low: the resolution is below the recommended resolution
idType	String	resident(resident registration certificate), driver(driver license), passport (passport)
keyValues	List
keyValues[0].key	String
keyValues[0].value	String		O
keyValues[0].bbox	Object	Coordinates of recognized area { x1, y1, x2, y2, x3, y3, x4, y4 }
keyValues[0].conf	Double	Confidence of the recognition result
boxes	List	List of bounding box coordinates
boxes[0]	Object	Coordinates of recognized area { x1, y1, x2, y2, x3, y3, x4, y4 }

• List included in KeyValues when "idType" is recognized as "resident"

key	value type	description
name	string	Recognized name
residentNumber	string	Recognized resident registration number
issueDate	string	Recognized issued date
issuer	string	Recognized issuer

• List to be included in KeyValues when "idType" is recognized as "driver"

key	value type	description
driverLicenseNumber	string	Recognized driver license number
licenseType	string	Recognized driver license type (Class 1 Normal, etc.) When the values are 2 or more, separate them with “/”
name	string	Recognized name
residentNumber	string	Recognized resident registration number
condition	string	Recognized driver license condition (If the field does not exist according to the driver's license, the value of the field is none)
serialNum	string	Recognized serial number
issueDate	string	Recognized issued date
issuer	string	Recognized issuer

• List included in KeyValues when "idType" is recognized as "passport"

key	value type	description
passportType	string	Recognized passport type
countryCode	string	Recognized country code
passportNo	string	Recognized passport number
surName	string	Recognized surname
givenName	string	Recognized name
nationality	string	Recognized nationality
dateOfBirth	string	Recognized birthdate
dateOfBirthYMD	string	Recognized birthdate (YYYYMMDD 8 digits)
sex	string	Recognized gender
dateOfIssue	string	Recognized issue date
dateOfIssueYMD	string	Recognized issue date (YYYYMMDD 8 digits)
dateOfExpiry	string	Recognized expiration date
dateOfExpiryYMD	string	Recognized expiration date (YYYYMMDD 8 digits)
koreanName	string	Recognized Korean name
personalNo	string	Recognized resident registration number
MRZ1	string	Machine readable zone 1
MRZ2	string	Machine readable zone 2

• Encrypted items (keyValues[0].value, etc.) are encrypted with the AES-256/CBC/PKCS7Padding method (using symmetric key).
• boxes[0]